Best Tools for JAVA

home *** CD-ROM | disk | FTP | other *** search

/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / RELEASE.ZIP / sub_arctic / lib / interactor.java < prev next >

Wrap

Java Source | 1996-10-04 | 81.8 KB | 2,055 lines

package sub_arctic.lib; import sub_arctic.input.pick_collector; import sub_arctic.constraints.constraint; import sub_arctic.constraints.std_constraint_consts; import sub_arctic.constraints.std_ext_constraint; import sub_arctic.constraints.value_provider; import sub_arctic.constraints.value_consumer; import sub_arctic.constraints.provider_part_ref; import sub_arctic.output.drawable; import java.util.Vector; import java.awt.Component; import java.awt.Point; import java.awt.Dimension; import java.awt.Rectangle; /** * This interface provides the API for all interactive objects that appear * on the screen and/or accept input. Currently all interactor objects * in the system are implemented by subclasses of the base_interactor * class. See that class for addition common methods and for information * about defaults. * * The API for interactors covers basic capabilities in 10 areas: * <ul> * <li> geometry management, * <li> coordinate system * <li> transformations, * <li> hierarchy management, * <li> traversal support, * <li> layout, * <li> picking, * <li> object status, * <li> output, * <li> user information, and * <li>debugging support. * </ul> * * See the user's manual for conceptual material related to each area * (each of these areas is covered by a sub-section of the user's manual) and * see the methods of base_interactor for additional details of each supported * routine. * * Note: due to limitations on some (most?) platforms that do not allow for * protected methods in interfaces, a number of routines here (and in the * interactor interface) that should be protected, are currently public. * These are marked by comments in the code, and will be reverted to protected * as soon as enough platforms allow. * * @author Scott Hudson */ public interface interactor extends interactor_consts, std_constraint_consts, value_provider, value_consumer { /*---------------------------------------------------------------------*/ /* Basic object geometry */ /*---------------------------------------------------------------------*/ /** * Position of the top-left corner of this object in the parent coordinate * system. If either coordinate is controlled by a constraint, it will be * brought up to date before this value is returned. * @return Point the position of the object. */ public Point pos(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * X position of the top-left corner of this object in the parent coordinate * system. If this coordinate is controlled by a constraint, it will be * brought up to date before this value is returned. * @return int the x position of the object. */ public int x(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Y position of the top-left corner of this object in the parent coordinate * system. If this coordinate is controlled by a constraint, it will be * brought up to date before this value is returned. * @return int the y position of the object. */ public int y(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Size of the object. If either the width or height of the object is * controlled by a constraint, it will be brought up to date before this * value is returned. * @return Dimension the size of the object. */ public Dimension size(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Width of the object. If this value is controlled by a constraint, it will * be brought up to date before being returned. * @return int the width of the object. */ public int w(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Height of the object. If this value is controlled by a constraint, it * will be brought up to date before being returned. * @return int the height of the object. */ public int h(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Bounding rectangle of the object (in parent's coordinate system). * @return Rectangle the bounding rectangle of the object. */ public Rectangle bound(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate if the object considers itself visible. If a constraint is * attached the value will be brought up-to-date with respect to the * constraint first. * @return boolean the visibility status of the object */ public boolean visible(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate if object is enabled. If a constraint is attached the value * will be brought up-to-date with respect to the constraint first. * * Note: currently setting an object disabled will keep it from being * picked by the normal picking mechanism. This will (normally) disable * positional inputs and as a side effect most focus based input (unless the * the object is already the focus). However, since enabled status was * added after many of the core interactor classes were created, for the * most part the interactors in the library do not yet properly reflect the * enable/disable status in their visual appearance. This is an important * deficiency which we hope to correct in future releases. * * @return boolean the enable status of the interactor. */ public boolean enabled(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /* STYLECHANGE_IGNORE_START */ // xx shouldn't that be styleChangeIgnoreStart (leave the identifiers alone!) /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return the value of part_a. Part_a is a generic value that may be * maintained by an interactor to represent some specific semantically * meaningful part of its state that it wants to make available for use * in the (lightweight) constraint system. For example, sliders make * their "thumb value" available as part_a. Here in the base class, * part_a is not implemented (it is intrinsically constrained to 0). * * @see sub_arctic.lib.interactor_with_parts * @see sub_arctic.lib.parent_with_parts * @return int the value of part_a (after constraint evaluation if necessary). */ public int part_a(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return the value of part_b. Part_b is a generic value that may be * maintained by an interactor to represent some specific semantically * meaningful part of its state that it wants to make available for use * in the (lightweight) constraint system. For example, sliders make * their "thumb value" available as part_b. Here in the base class, * part_b is not implemented (it is intrinsically constrained to 0). * * @see sub_arctic.lib.interactor_with_parts * @see sub_arctic.lib.parent_with_parts * @return int the value of part_b (after constraint evaluation if necessary). */ public int part_b(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Get the specified component (X, Y, W, or H) or of object's geometry. This * also now works for VISIBLE, ENABLED, PART_A, and PART_B. * @param what_code part number whose value is being requested. * @return int the value of the requested part (after brining any attached * constraints up-to-date). */ public int get_part(int what_code) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set position of this object in parent coordinate system. * * @param int yv y coordinate of the position. * @param int xv x coordinate of the position. */ public void set_pos(int xv, int yv) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set position of this object in parent coordinate system. * * @param Point p the new position. */ public void set_pos(Point p) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set x component of position in parent coordinate system. * @param int v the new value for x. */ public void set_x(int v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set y component of position in parent coordinate system. * @param int v the new value for y. */ public void set_y(int v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set the size of the object. * @param int wv the new value for w. * @param int hv the new value for h. */ public void set_size(int wv, int hv) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set width of object. * @param int v the new value for y. */ public void set_w(int v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set height of object. * @param int v the new value for the height. */ public void set_h(int v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set the visibility of the interactor. * @param boolean v the new visibility status. */ public void set_visible(boolean v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set the enabled status of the interactor. * @param boolean v new value of enabled. */ public void set_enabled(boolean v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set part_a of object. If part is controlled by a constraint, an * exception is thrown. * * @param int v the new value for part_a */ public void set_part_a(int v) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set part_b of object. If part is controlled by a constraint, an * exception is thrown. * * @param int v the new value for part_b */ public void set_part_b(int v) ; /*---------------------------------------------------------------------*/ /* Coordinate system transformations */ /*---------------------------------------------------------------------*/ /** * Transform a point in the local coordinate space into the global space * (that is the coordinate system of the top_level object which roots the * interactor tree this object is in). * * @param int xv x coordinate of point to transform. * @param int yv y coordinate of point to transform. * @return Point resulting point. */ public Point local_to_global(int xv, int yv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a point in the local coordinate space into the global space * (that is the coordinate system of the top_level object which roots the * interactor tree this object is in). * * @param Point local_pt point to transform. * @return Point resulting point. */ public Point local_to_global(Point local_pt); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a point in global coordinate space (that is the coordinate * system of the top_level object which roots the interactor tree this * object is in) into the local space of the object. * * @param int xv x coordinate of point to transform. * @param int yv y coordinate of point to transform. * @return Point resulting point. */ public Point global_to_local(int xv, int yv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a point in global coordinate space (that is the coordinate * system of the top_level object which roots the interactor tree this * object is in) into the local space of the object. * * @param Point global_pt point to transform. * @return Point resulting point. */ public Point global_to_local(Point global_pt); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a point from parent's coordinate space to local coordinates of * this object. * * @param int xv x coordinate of point to transform. * @param int yv y coordinate of point to transform. * @return Point resulting point. */ public Point into_local(int xv, int yv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a point from parent's coordinate space to local coordinates of * this object. * * @param Point parent_pt point to transform. * @return Point resulting point. */ public Point into_local(Point parent_pt); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform an x value from parent's coordinate space to local coords. * * @param int xv x coordinate of to transform. * @return int resulting x coordinate. */ public int x_into_local(int xv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform an y value from parent's coordinate space to local coords. * * @param int yv y coordinate of to transform. * @return int resulting y coordinate. */ public int y_into_local(int yv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a local point into the parent's coordinate space. * * @param Point local_pt point to transform. * @return Point resulting point. */ public Point into_parent(Point local_pt); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform a local point into the parent's coordinate space. * * @param int xv x coordinate of point to transform. * @param int yv y coordinate of point to transform. * @return Point resulting point. */ public Point into_parent(int xv, int yv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform an x value form local coordinates into the parent's coordinate * space. * * @param int xv x coordinate of to transform. * @return int resulting x coordinate. */ public int x_into_parent(int xv); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Transform an y value form local coordinates into the parent's coordinate * space. * * @param int yv y coordinate of to transform. * @return int resulting y coordinate. */ public int y_into_parent(int yv); /*---------------------------------------------------------------------*/ /* Hierarchy management */ /*---------------------------------------------------------------------*/ /** * Return the parent of this interactor. * @return interactor the parent of this interactor or null if this object * is an orphan or is a top_level (root) interactor. */ public interactor parent(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set the parent of this interactor. * * Warning: this method should be protected (but isn't since various * implementations don't allow protected in interfaces). This method should * not be invoked from "outside the system". Always use the normal child * manipulation routines instead. * * @param interactor par new parent for this object. */ public void set_parent(interactor par) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Retrieve the top_level interactor (if any) that this object is installed * (perhaps several levels down) under. This top_level interactor provides * the "global" coordinate space for this interactor. Null is returned if * this object is not currently installed somewhere under a top_level * interactor. * * @return top_level the top_level object we are installed under or null if * there is no such object. */ public top_level get_top_level(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Retrieve the AWT component that this sub_arctic object is drawn within. * If this object is not part of an active interface, null will be returned. * * @result Component the AWT component that this sub_arctic object is drawn * within or null if the object is "floating". */ public Component get_awt_component(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return the child index of this interactor (within its parent). * This value is obviously not going to be correct for orphan objects. * @return int index of this interactor within its parent's child list. */ public int child_index(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set the child index of this interactor (within its parent). * * Warning: this method should be protected (but isn't since various * implementations don't allow protected in interfaces). This method should * not be invoked except from the within the normal child manipulation * routines.Always use those routines instead. * * @param int indx the new index of the child. */ public void set_child_index(int indx); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return the previous sibling of this object (or null if there is none). * @return interactor the child before this one in its parent's child list or * null if there is no such object. */ public interactor prev_sibling(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return the next sibling of this object (or null if there is none). * @return interactor the child after this one in its parent's child list or * null if there is no such object. */ public interactor next_sibling(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate whether this interactor supports children. Interactors that * support children will have their SUPPORTS_CHILDREN flag set. * @return boolean indicating whether this object supports children. */ public boolean supports_children(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate whether this interactor uses a fixed set of children. This is * done if the interactor assigns fixed roles/meanings to particular * children, or for some other reason limits its total number of children. * If this is not set, then the child list is expandable and the system * will move entries over to fill in null children (although you cannot rely * on this behavior since it is possible to explicitly set a child at a * given index to null and sneak nulls into the child list in other ways). * If this is set, then removed children will be set to null, and the child * list will not be otherwise modified. In addition, if this is set, then * operations that would normally reorder children throw an exception * instead. An object which uses fixed children will have its * FIXED_CHILDREN flag set. * * @return boolean indicating whether this object supports fixed children. */ public boolean fixed_children(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate the number of children this interactor currently has. For * interactors with fixed children, the interactor will always have this * this number, hence it is also the maximum number of children. * Interactors that do not support children always return 0. Note: there * may be null children in the child list but they are counted as children * here. * * @return int number of slots in this object's child list. */ public int num_children(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return the child at the given index int the child list (whose first * element is at index 0). If the index given is beyond the range of the * current child list, or the interactor does not support children, then * null is returned. Requests for negative children cause an exception. * Note that child lists may contain null children. * * @param int i the index of the requested child. * @return interactor the child object at the requested index. */ public interactor child(int i) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Set the child at the given index replacing any child that was previously * there. The child list will be expanded as necessary to accommodate the * given child. If the child list is expanded, missing children will be * set to null. * * @param int at_indx position in the child list to replace. * @param interactor chld the child object to place at that position. */ public void set_child(int at_indx, interactor chld) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Add a child to the end of the child list. * @param interactor chld the child to add. */ public void add_child(interactor chld) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Insert a child at the given location, moving current children at or * after that index further down in the list. */ public void insert_child(int at_indx, interactor chld) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Remove the child found at the given index and return it. For * interactors with fixed children, the child slot at the index is set * to null. For other interactors, later children are moved over in the * list to fill in the gap. * * @param int at_indx the index to remove the child from. */ public interactor remove_child(int at_indx) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Remove the given child from the child list. For interactors with * fixed children, the child slot is set to null. For other interactors, * later children are moved up in the list to fill in the gap. If the * child is not in the child list, nothing happens. * * @param interactor the_child the child to be removed. */ public void remove_child(interactor the_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Find the given child in the child list and return its index. If the * child is no in the child list -1 is returned. * * @param interactor the_child the child we are searching for. * @return int the index of that child in the child list or -1 if the child * is not found. */ public int find_child(interactor the_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the child currently at the given index in the child list to the * top in drawing order (which is last in the list). * * @param int chld_indx the index of the child to move. */ public void move_child_to_top(int chld_indx) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Move the given child to the top of the child list in drawing order * (which is last in the list). If the child is not in the list, nothing * happens. * * @param interactor the_child the child to move. */ public void move_child_to_top(interactor the_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the child currently at the given index in the child list to the * bottom in drawing order (which is first in the list). * * @param int chld_indx the index of the child to move. */ public void move_child_to_bottom(int chld_indx) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the given child to the bottom of the child list in drawing order * (which is first in the list). If the child is not in the list, nothing * happens. * * @param interactor the_child the child to move. */ public void move_child_to_bottom(interactor the_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the child currently at the given index in the child list up one * position in drawing order (which is one position further into the list). * * @param int chld_indx the index of the child to move. */ public void move_child_upward(int chld_indx) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the given child up one position in drawing order of the child list * (which is later in the list). If the child is not in the list, nothing * happens. * * @param interactor the_child the child to move. */ public void move_child_upward(interactor the_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the child currently at the given index in the child list down one * position in drawing order (which is one position earlier in the list). * * @param int chld_indx the index of the child to move. */ public void move_child_downward(int chld_indx) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move the given child down one position in drawing order of the child list * (which is earlier in the list). If the child is not in the list, nothing * happens. * * @param interactor the_child the child to move. */ public void move_child_downward(interactor the_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move this object to the top of its parent's drawing order (last in * its child list). */ public void move_to_top() ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move this object to the bottom of its parent's drawing order (first in * its child list). */ public void move_to_bottom() ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move this object one position higher in its parent's drawing order * (which is one position further into its child list). */ public void move_upward() ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Move this object one position lower in its parent's drawing order * (which is one position earlier in its child list). */ public void move_downward() ; /*---------------------------------------------------------------------*/ /* Layout */ /*---------------------------------------------------------------------*/ /** * Indicate which parts (coordinates/sizes/values) of this object are * intrinsically constrained by the internals of the object. For, example * an icon object with a fixed size image would intrinsically constrain * its width and height. The result is reported as an integer formed from * or-ing together zero or more of the constants: X, Y, W, H, VISIBLE, * ENABLED, PART_A or PART_B (for the icon described above that would be * W | H). * * @return int bitset indicating which parts of the object are intrinsically * constrained. */ public int intrinsic_constraints(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate which parts (coordinates/sizes/values) of this object are * currently constrained. This always includes the intrinsic constraints, * but may also indicate other constraints that have been applied to the * object. The result is reported as an integer formed from or-ing * together zero or more of the constants: X, Y, W, H, VISIBLE, ENABLED, * PART_A and PART_B. Values that are constrained may not be assigned to * directly (an exception will be thrown). * * @param int bitset indicating which parts of the object are constrained. */ public int active_constraints(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate whether a specific part is currently constrained. The query * argument should be one of the constants: X, Y, W, H, VISIBLE, ENABLED, * PART_A, or PART_B. Values that are constrained may not be assigned to * (an exception will be thrown). * * @param int coord_code the object part we are enquiring about. * @return boolean indicating whether it is constrained. */ public boolean is_constrained(int coord_code); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to the specified part (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B). * @param int coord_code the code for the object part in question. * @return constraint the constraint attached to the given part. */ public constraint constraint_on(int coord_code) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to x. * @return constraint the constraint attached to x. */ public constraint x_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to y. * @return constraint the constraint attached to x. */ public constraint y_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to w. * @return constraint the constraint attached to w. */ public constraint w_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to h. * @return constraint the constraint attached to h. */ public constraint h_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to visible. * @return constraint the constraint attached to visible. */ public constraint visible_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to enabled. * @return constraint the constraint attached to enabled. */ public constraint enabled_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to part_a. * @return constraint the constraint attached to part_a. */ public constraint part_a_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Return a constraint object representing the constraint (if any) attached * to part_b. * @return constraint the constraint attached to part_a. */ public constraint part_b_constraint(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the given value (one of X, Y, W, H, VISIBLE, * ENABLED, PART_A, or PART_B). This replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param int coord_code code for the part whose constraint we * replace. * @param constraint a_constraint the constraint to replace it with. */ public void set_constraint(int coord_code, constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the given value (one * of X, Y, W, H, VISIBLE, ENABLED, PART_A, PART_B). This replaces any * constraint currently in place. However, an attempt to replace an * intrinsic constraint will result in an exception. * * @param int coord_code code for the part whose constraint we * replace. * @param constraint a_constraint the constraint to replace it with. */ public void set_constraint(int code, value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the x value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. Only * horizontally oriented constraints can be attached to x (if a vertically * oriented value is need, use an external constraint). * * @param constraint a_constraint the constraint to replace it with. */ public void set_x_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the x value of * this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_x_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the x value of this object. * This replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_x_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the y value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. Only * vertically oriented constraints can be attached to y (if a horizontally * oriented value is need, use an external constraint). * * @param constraint a_constraint the constraint to replace it with. */ public void set_y_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the y value of * this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_y_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the y value of this object. * This replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_y_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the w value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. Only * horizontally oriented constraints can be attached to w (if a vertically * oriented value is need, use an external constraint). * * @param constraint a_constraint the constraint to replace it with. */ public void set_w_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the w value of * this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_w_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the w value of this object. * This replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_w_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the h value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. Only * vertically oriented constraints can be attached to h (if a horizontally * oriented value is need, use an external constraint). * * @param constraint a_constraint the constraint to replace it with. */ public void set_h_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the h value of * this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_h_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the h value of this object. * This replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_h_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the visible value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param constraint a_constraint the constraint to replace it with. */ public void set_visible_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the visible value * of this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_visible_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the visible value of this * object. This replaces any constraint currently in place. However, an * attempt to replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_visible_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the enabled value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param constraint a_constraint the constraint to replace it with. */ public void set_enabled_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the enabled value * of this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_enabled_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the enabled value of this * object. This replaces any constraint currently in place. However, an * attempt to replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_enabled_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the part_a value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param constraint a_constraint the constraint to replace it with. */ public void set_part_a_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the part_a value of * this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_part_a_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the part_a value of this * object. This replaces any constraint currently in place. However, an * attempt to replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_part_a_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a constraint on the part_b value of this object. This * replaces any constraint currently in place. However, an attempt to * replace an intrinsic constraint will result in an exception. * * @param constraint a_constraint the constraint to replace it with. */ public void set_part_b_constraint(constraint a_constraint) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish an "external" or "heavyweight" constraint on the part_b value of * this object. This attaches a value exported by a particular part of * some value_provider object and replaces any constraint currently in * place. However, an attempt to replace an intrinsic constraint will * result in an exception. * * @param value_provider ext_obj the external object providing the value. * @param int ext_part the part number of the part of that object * providing the value. */ public void set_part_b_constraint(value_provider ext_obj, int ext_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Establish a standard external constraint on the part_b value of this * object. This replaces any constraint currently in place. However, an * attempt to replace an intrinsic constraint will result in an exception. * * @param std_ext_constraint ext_cnstr the constraint to attach. */ public void set_part_b_constraint(std_ext_constraint ext_cnstr) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate which values are currently marked as potentially out of * date with respect to their constraints. Typically this information * is needed only by the constraint system, since values are generally * brought up to date whenever they are requested. * * @returns int a bitset indicating the parts of this object which are * currently marked out-of-date. */ public int marked_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark the given value as out of date. This will recursively mark * anything that directly or indirectly depends on the given value. This * should normally only be called by the constraint system, since setting * values via set_*() will automatically call this routine. * * @param int the part to mark out-of-date. This should be one of the * values: X, Y, W, H, ENABLED, PART_A, or PART_B. */ public void mark_ood(int coord_code) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark all geometric parts of this object out of date. This happens for * example when we reparent it. */ public void mark_all_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark x value and anything that directly or indirectly depends on it as * out-of-date. */ public void mark_x_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark y value and anything that directly or indirectly depends on it as * out-of-date. */ public void mark_y_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark w value and anything that directly or indirectly depends on it as * out-of-date. */ public void mark_w_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark h value and anything that directly or indirectly depends on it as * out-of-date. */ public void mark_h_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark visible value and anything that directly or indirectly depends on * it as out-of-date. */ public void mark_visible_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark enabled value and anything that directly or indirectly depends on * it as out-of-date. */ public void mark_enabled_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark part_a value and anything that directly or indirectly depends on it * as out-of-date. */ public void mark_part_a_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark part_b value and anything that directly or indirectly depends on it * as out-of-date. */ public void mark_part_b_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Mark all our geometric parts out-of-date and tell all potentially * dependent objects that all our parts are out-of-date (this gets done * when we move around in the hierarchy). This affects, x, y, w, and h, * but not visible, enabled, part_a, or part_b. */ public void mark_reparented_ood(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Inform the object that the indicated part of a potentially related object * is out-of-date (this is called from ood_inform_all()). The related * object can be one of OBJCODE_SELF, OBJCODE_PARENT, OBJCODE_SOME_CHILD, * OBJCODE_NEXT_SIBLING, or OBJCODE_PREV_SIBLING, and the indicated part * can be X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B. * * The nth_child parameter is used only if OBJCODE_SOME_CHILD is passed, * in which case it indicates the index of the child in question. * If parts of this object are actually dependent upon the given part they * are marked out-of-date and the mark out-of-date traversal is continued * recursively from them. If not, we do nothing. * * @param int from_type the type of object we are being informed by (must be * one of OBJCODE_SELF, OBJCODE_PARENT, * OBJCODE_SOME_CHILD, OBJCODE_NEXT_SIBLING, or * OBJCODE_PREV_SIBLING). * @param int from_part the part code of the part of that object which is * informing us that it is out-of-date. * @param int nth_child if from_type is OBJCODE_SOME_CHILD, this parameter * indicates which child it is (otherwise it is ignored). */ public void inform_ood( int from_obj_type, int from_part, int nth_child) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Handle a cycle detected in constraints on a given part of this object. * If this routine returns true, then evaluation proceeds. If this returns * false then, the current value of the attribute (which may have been set * by this routine) is left in place but marked up-to-date. * * @see sub_arctic.lib.manager#handle_cycle * @param int part_code the part of this object that involves a cycle. * @return boolean indicating whether we should proceed with evaluation. */ public boolean handle_cycle(int part_code); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Bring the indicated value up to date with respect to any defining * constraints. This routine does not typically need to be called * explicitly since normal requests for values do evaluations before * returning. * * @param int coord_code the part whose value should be evaluated. */ public void eval(int coord_code) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring x up to date with respect to any defining constraint. */ public void eval_x(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring y up to date with respect to any defining constraint. */ public void eval_y(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring w up to date with respect to any defining constraint. */ public void eval_w(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring h up to date with respect to any defining constraint. */ public void eval_h(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring visible up to date with respect to any defining constraint. */ public void eval_visible(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring enabled up to date with respect to any defining constraint. */ public void eval_enabled(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring part_a up to date with respect to any defining constraint. */ public void eval_part_a(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Bring part_b up to date with respect to any defining constraint. */ public void eval_part_b(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Get the external value provider (if any) associated with the given * part value (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B). Returns * null if there is no external provider. * * @param int for_part the part we are asking about. * @return provider_part_ref the external value provider associated with that * part, or null if there is none. */ public provider_part_ref get_external_constraint(int for_part); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Get an up-to-date copy of a particular part value(X, Y, W, H, VISIBLE, * ENABLED, PART_A, or PART_B). An Integer object will be returned. * * @param int part_number the part being requested. * @return Object an Integer object containing the value of the requested * part. */ public Object get_value(int part_number) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * A custom function accessible in the constraint system. This function * is accessible from the (lightweight) constraint system and can be * overridden by particular subclasses to perform custom computations * associated with that class. This version is passed a single parameter * value derived from a depended upon object, plus a constant value taken * from the constraint. * * Important note: for the constraint system to work correctly, this * function must compute its value solely on its parameters and not access * additional information from this object or other objects (since the * attribute constrained to the result of this function will not hear about * changes and be properly updated). * * @param int val1 a value from a depended upon object. * @param int const_val a constant value taken from the constraint. * @returns int the result of evaluating of the function. */ public int custom_fun1(int val1, int const_val); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * A custom function accessible in the constraint system. This function * is accessible from the (lightweight) constraint system and can be * overridden by particular subclasses to perform custom computations * associated with that class. This version is passed two parameter values * derived from a depended upon object, plus a constant value taken from the * constraint. * * Important note: for the constraint system to work correctly, this * function must compute its value solely on its parameters and not access * additional information from this object or other objects (since the * attribute constrained to the result of this function will not hear about * changes and be properly updated). * * @param int val1 a value from a depended upon object. * @param int val2 another value from a depended upon object. * @param int const_val a constant value taken from the constraint. * @returns int the result of evaluating the function. */ public int custom_fun2(int val1, int val2, int const_val); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Register something as interested in (dependent on) one of the parts * (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B) of this object. The * entity registered is a part within a value_consumer object (typically * an external_constraint). Whenever the part value in question is marked * out-of-date, the value_ood() method is invoked on each currently * registered (object,part) pair. * * @param int on_part_num the part of this object that the * dependency is being attached to. * @param value_consumer dep_obj the object that is dependent. * @param int dep_part the part within that object which is * dependent. */ public void attach_dependent( int on_part_num, value_consumer dep_obj, int dep_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Remove an (object,part) pair from the dependent (interested in) list * associated with a particular part of this object. * * @param int on_part_num the part of this object that the * dependency is attached to. * @param value_consumer dep_obj the object that was dependent. * @param int dep_part the part within that object which was * dependent. */ public void detach_dependent( int on_part_num, value_consumer dep_obj, int dep_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate that a part value (X, Y, W, H, VISIBLE, ENABLED, PART_A, or * PART_B) with an external constraint attached should be marked out-of-date * because something it depends on (externally) is out-of-date. * * @param int for_part_here part within this object that should be * marked out-of-date. * @param value_provider prov_obj object that we depend on. * @param int prov_part part within that object that is */ public void value_ood( int for_part_here, value_provider prov_obj, int prov_part) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Do the constraint evaluation necessary to make sure all visible objects * in the subtree rooted at this object have up-to-date bounds (and other * information) prior to drawing. This routine implements the "configure" * pass which occurs right before the pass that does the actual drawing. * * Important note: In addition to the work done in the base_interactor * class (which should almost always be done by invoking super() from any * subclass implementations), each subclass should also be certain to update * anything which could effect its bounds here, and not in * draw_self_local(). So for example if the height of an object depends on a * font that might have changed, the potentially new height must be computed * and set here and not in draw_self_local(). In general, for things to work * out right it must be the case that this object's bound is correct once * this method returns. The reason for this is that by the time * draw_self_local() is called, the clipping region corresponding to the * bound of this object will have already been set and changing the bound * then will not modify the clipping region accordingly (so the drawing may * be incorrect). */ public void configure(); /*---------------------------------------------------------------------*/ /* Picking */ /*---------------------------------------------------------------------*/ /** * Determine if the given point (in the local coordinates of this object) * is inside the extent of this object's normal bound. You should not * normally override this routine to handle picking of non-rectangular * objects. Do that in picked_by() instead. * * @see #picked_by * @param int pt_x x coordinate of the query point. * @param int pt_y y coordinate of the query point. * @return boolean indicating whether the point is inside the objects * bounding box. */ public boolean inside_bounds(int pt_x, int pt_y); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Determine if the given point (in the local coordinates of this object) * is inside the extent of the object picking purposes. Be default, this * method just checks the normal bound (bounding box), however, it can * be overridden to support accurate picking of non-rectangular objects. * * @see #inside_bounds * @param int pt_x x coordinate of the query point. * @param int pt_y y coordinate of the query point. * @return boolean indicating whether the point is inside the objects * bounding box. */ public boolean picked_by(int pt_x, int pt_y); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Determine if this object and/or any of its decedent objects is "picked" * by the the given point. If it is, it must add itself to the end of the * given given pick_collection by calling report_pick(). If not, it should * leave the pick_collector as is. * * This method is also responsible for recursively invoking itself as * appropriate for its children (this is usually done using the * base_interactor.pick_within_children() utility routine). By default we * pick against any children first (since they are by default drawn last) * and then this object. However, if the drawing order is changed from the * default, this method must be changed to reflect (the reverse of) that * non-standard order. For example, if this object does drawing both under * and on top of its children, two sets of part specific tests would * typically be needed, one before recursively picking the children, and one * after. * * @see sub_arctic.lib.base_interactor#pick_within_children * @param int pt_x x coordinate of the query point. * @param int pt_y y coordinate of the query point. * @param pick_collector pick_list object that collects and returns pick * results. */ public void pick(int pt_x, int pt_y, pick_collector pick_list) ; /*---------------------------------------------------------------------*/ /* Generic traversal support */ /*---------------------------------------------------------------------*/ /** * Do a traversal of the interactor tree to collect nodes meeting some * criteria (or perform actions on qualifying nodes). Traversals are * given a specialized "kind" so that subclasses can recognize and * override behavior for certain traversals, while keeping default behavior * for the rest. In addition, several traversal orders are provided. * Qualification for collection (or action) is done by an inclusion test * predicate object. This predicate is given the interactor in question * as well as some (optional) data specific to the predicate. This * data is passed in from the root of the traversal and (optionally) * transformed from parent to child values as the traversal proceeds. * Objects are collected (along with optional additional data) by adding * them to a pick_collector object. Recursive traversal is stopped when * either leaves are reached or the continue_test predicate for an * interior node fails (in which case its children will not be visited). * * Examples of possible traversals include: * Replacement for the normal pick operation: * <pre> * traverse_and_collect(pick_trav, TRAV_DRAW, pt_inside_bounds, pt_inside_bounds, * coord_parent_to_local, pick_pt, result); * </pre> * and a tree dump: * <pre> * traverse_and_collect(dump_trav, TRAV_PRE, dump_interactor, incr_int, * null, new Integer(0), result) * </pre> * where dump_interactor printed to the node to System.out at the indentation * level of its Integer parameter, but always returns false * * @param traversal_kind a unique integer (i.e., generated by * manager.unique_int()) that represents the kind * of traversal being performed. * @param traversal_order one of TRAV_DRAW, TRAV_PICK, TRAV_PRE, or * TRAV_POST indicating drawing order, pick order, * left-to-right pre-order, or left-to-right * post-order traversal. * @param inclusion_test an interactor predicate object which is to * perform the inclusion test for this traversal. * If the traversal is being done for its action * side-effects (rather than a collection, per se) * then this object's test() method should perform * that action on selected nodes. A null * inclusion_test is treated as a function that * selects everything (always returns true). * @param continue_test an interactor_predicate object which determines * if the given object's children are traversed. * If this method returns false, then the children * will not be visited. A null continue_test is * is treated as a function that always returns * true. * @param xform_parent_to_child object containing a method to transform the * parameters data (passed to the inclusion_test) * from its parent condition to the condition * suitable for use by a given child. This can * be used, for example, to transform a point from * the parent's coordinates into those of a child. * A null object is treated as the identity * transformation (i.e. uses the parent's * parameters directly for all children). * * @param parameters the initial parameters data passed to the * inclusion_test at the root, then transformed by * xform_parent_to_child for recursive calls on * children. * @param collection_result a pick_collector object which holds a list of * interactors collected by this traversal (and * optional associated data). If an object * determines that it should be a part of the * collection of this traversal, it should add * itself to this collection by calling its * report_pick() method. */ public void traverse_and_collect( int traversal_kind, int traversal_order, interactor_pred inclusion_test, interactor_pred continue_test, traversal_xform xform_parent_to_child, Object parameters, pick_collector collection_result) ; /*---------------------------------------------------------------------*/ /* Status */ /*---------------------------------------------------------------------*/ /** * Determine if a particular bit (or bits) is set in the flag set for the * interactor. In the case of testing for multiple flag bits, they must * all be set to get a result of true. See interactor_consts for * possible values that can be queried. * * @see sub_arctic.lib.interactor_consts * @param int mask_value the flag bit or bits we are enquiring about. * @return boolean indicating whether the bit or bits are (all) set. */ public boolean flag_is_set(int mask_value); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Determine if a particular bit (or bits) is set in the constraint_flag * set for the interactor. In the case of testing for multiple * constraint_flag bits, they must all be set to get a result of true. * See interactor_consts for possible values that can be queried. */ public boolean constraint_flag_is_set(int mask_value); /*---------------------------------------------------------------------*/ /* Output */ /*---------------------------------------------------------------------*/ /** * Do a trivial reject test that indicates whether the bounds of this object * are entirely outside the clipping region of the given drawable object. * The drawable object is assumed to be configured for our parent's * coordinate system. Returns true if nothing inside our bounds will * survive the clip and hence need not be drawn. This test is used in * draw_self() to avoid drawing anything for the object if none of it * could show up anyway. * * @see #draw_self * @param drawable d the drawable whose current clipping we are * testing against. * @param Rectangle bounding_box the bounding box we are comparing that with. */ public boolean trivial_reject(drawable d); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Draw the object's current appearance. The drawable object passed in * is still set up in the parent's coordinate system. This routine normally * sets up the transformation for the local coordinate system, then calls * draw_self_local(). Consequently, most interactors do not override this * routine, but instead override base_interactor.draw_self_local(). * * @see sub_arctic.lib.base_interactor#draw_self_local * @param drawable parent_d a drawable (still set up for the parent) to * produce output on. */ public void draw_self(drawable d) ; /*---------------------------------------------------------------------*/ /* Damage/redraw management */ /*---------------------------------------------------------------------*/ /** * Indicate that the object has been modified in such as way that its * appearance within the given area of the screen (expressed in local * coordinates) might change and needs to be redrawn. This does not * update any attributes controlling size and position of this object * or any other object up the parent chain, but instead uses existing * values (reflecting the existing sizes and positions). If you need to * damage this object's updated position, explicitly update it first. * * @param Point top_left top left corner of the damaged rectangle. * @param Dimension sz size of the damaged rectangle. */ public void damage_self(Point top_left, Dimension sz) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate that the object has been modified in such as way that its * appearance within the given area of the screen (expressed in local * coordinates) might change and needs to be redrawn. This does not * update any attributes controlling size and position of this object * or any other object up the parent chain, but instead uses existing * values (reflecting the existing sizes and positions). If you need to * damage this object's updated position, explicitly update it first. * * @param int left left edge of the damaged rectangle. * @param int top top edge of the damaged rectangle. * @param int wid width of the damaged rectangle. * @param int hi height of the damaged rectangle. */ public void damage_self(int left, int top, int wid, int hi) ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate that the object has been modified in such as way that any or * all of its appearance may change and its area of the screen needs * to be redrawn. * */ public void damage_self() ; /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate that a change to a child (or grandchild, etc.) affects the * given screen region (expressed in the coordinates of this object). * This is responsible for passing damage up the tree. * * @param Point top_left top left corner of the damaged rectangle. * @param Dimension sz size of the damaged rectangle. */ public void damage_from_child(Point top_left, Dimension sz) ; /*---------------------------------------------------------------------*/ /* Feature points */ /*---------------------------------------------------------------------*/ /** * The number of "feature points" of an object. Feature points are points * within an object which are interesting for alignment, snapping or * other purposes. They are used by the move_drag and snap_drag agents. * * Feature points are expressed in the local coordinates of the object in * question. Objects by default provide 5 points corresponding to their * corners and center. Constants representing indexes for these standard * points are defined in interactor_consts. Additional points with * specialized meanings may be provided by subclasses. * * @see sub_arctic.input.move_drag_focus_agent * @see sub_arctic.input.move_draggable * @see sub_arctic.input.move_drag_filter * @see sub_arctic.input.std_drag_filters * @see sub_arctic.input.snap_drag_agent * @see sub_arctic.input.snap_draggable * @see sub_arctic.input.snap_targetable * @see sub_arctic.lib.interactor_consts * * @return int the number of feature points this object has. */ public int num_feature_points(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Access to the "feature points" of an object (by index). Feature points * are points within an object which are interesting for alignment, * snapping or other purposes. They are used by the move_drag and * snap_drag agents. * * Feature points are expressed in the local coordinates of the object in * question. Objects by default provide 5 points corresponding to their * corners and center. Constants representing indexes for these standard * points are defined in interactor_consts. Additional points with * specialized meanings may be provided by subclasses. If an index out of * range is given the top-left corner (index FEATURE_TOP_LEFT which is * always 0,0) is returned. * * @see sub_arctic.input.move_drag_focus_agent * @see sub_arctic.input.move_draggable * @see sub_arctic.input.move_drag_filter * @see sub_arctic.input.std_drag_filters * @see sub_arctic.input.snap_drag_agent * @see sub_arctic.input.snap_draggable * @see sub_arctic.input.snap_targetable * @see sub_arctic.lib.interactor_consts * * @param int indx the index of the requested feature point. * @return Point the location of the requested feature point in local * coordinates. */ public Point feature_point(int indx); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Indicate whether the indicated "feature point" of an object is * considered to be enabled. Feature points are points within an object * which are interesting for alignment, snapping or other purposes. They are * used by the move_drag and snap_drag agents. * * Feature points are expressed in the local coordinates of the object in * question. Objects by default provide 5 points corresponding to their * corners and center. Constants representing indexes for these standard * points are defined in interactor_consts. Additional points with * specialized meanings may be provided by subclasses. * * By default all standard feature points are always enabled. If an index * out of range is given false will always be returned. * * @see sub_arctic.input.move_drag_focus_agent * @see sub_arctic.input.move_draggable * @see sub_arctic.input.move_drag_filter * @see sub_arctic.input.std_drag_filters * @see sub_arctic.input.snap_drag_agent * @see sub_arctic.input.snap_draggable * @see sub_arctic.input.snap_targetable * @see sub_arctic.lib.interactor_consts * * @param int indx the index of the feature point in question. * @return boolean indicating whether it is enabled. */ public boolean feature_point_enabled(int indx); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** Indicate the current "feature point" of an object. This point will be * used by the move_drag agent to control dragging. Feature points are * points within an object which are interesting for alignment, snapping * or other purposes. The current feature point is used by the move_drag * agent. See that agent for complete details. * * Feature points are expressed in the local coordinates of the object in * question. Objects by default provide 5 points corresponding to their * corners and center. Constants representing indexes for these standard * points are defined in interactor_consts. Additional points with * specialized meanings may be provided by subclasses. * * Note: this routine and the ones that use it ignore the enable status * of the point as returned by feature_point_enabled(). This routine * defaults to the top left corner of the object. * * @see sub_arctic.input.move_drag_focus_agent * @see sub_arctic.input.move_draggable * @see sub_arctic.input.move_drag_filter * @see sub_arctic.input.std_drag_filters * @see sub_arctic.lib.interactor_consts * * @return the index of the current feature point. */ public int drag_feature_point(); /*---------------------------------------------------------------------*/ /* User Info */ /*---------------------------------------------------------------------*/ /** * Access to uninterpreted "user information" that we are holding for the * user of this object. This information is for use of the user or * application only and is typically used to associated application specific * information with a particular interactor object. This information can be * entered using set_user_info(). It is not modified by the toolkit, and * can later be retrieved with this routine as needed. * * @see #set_user_info * @returns Object the user info object attached to this interactor. */ public Object user_info(); /** * Set the uninterpreted "user information" that we are holding for the * user of this object. This information is for use of the user or * application only and is typically used to associated application specific * information with a particular interactor object. This information can be * entered using this routine. It is not modified by the toolkit, and can * later be retrieved with user_info() as needed. * * @see #user_info * @param Object user_inf the object to associate with this interactor. */ public void set_user_info(Object user_inf); /*---------------------------------------------------------------------*/ /* Debugging */ /*---------------------------------------------------------------------*/ /** * Convert to a human readable string. * @return String a human readable dump of the object. */ public String toString(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /** * Convert to a small tag string which indicates the type of interactor * along with a (hopefully unique) integer (its hashCode) that can * be used to identify it during debugging. * @return String an terse identifying tag string for the object. */ public String tag_str(); /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ /* STYLECHANGE_IGNORE_STOP */ /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */ } /*======================= TERMS AND CONDITIONS OF USE ==================== This file is part of the subArctic user interface toolkit. Copyright (c) 1996 Scott Hudson and Ian Smith All rights reserved. Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this software in executable form for any purpose, and permission is also granted, to use, copy, and modify, redistribute for personal and internal use only (but not redistribute for profit) this software in source form, provided that the above copyright notice and this notice appears in all copies of this software, that this copyright appears in all supporting documentation, and that the name, logo, or any other symbol of the Georgia Institute of Technology or other employers of the authors or contributors is not be used in advertising or publicity pertaining to distribution of this software except in conjunction with these notices. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS, OR THEIR EMPLOYERS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF THE AUTHORS, CONTRIBUTORS, OR THEIR EMPLOYERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE AUTHORS AND THEIR EMPLOYER HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. These terms of use are subject to change in future version and releases. The current release and additional information about this software can be found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/ ========================================================================*/